vfile

What is vfile?

The vfile npm package is a virtual file format for text processing systems, which allows for the manipulation and handling of file-related information in a structured and consistent way. It is commonly used in projects involving the processing of markdown, text, and similar content, providing a standardized interface for plugins and utilities.

What are vfile's main functionalities?

Creating and modifying virtual files

This feature allows users to create a new virtual file and modify its contents. The example demonstrates creating a vfile with initial content and then appending additional text to it.

const vfile = require('vfile');

const file = vfile({path: './example.txt', contents: 'Hello, world!'});
file.contents += ' Modified content.';
console.log(file.contents);

Accessing file metadata

This feature enables users to access metadata of the file such as the path and basename. The example shows how to create a vfile and retrieve its path and basename properties.

const vfile = require('vfile');

const file = vfile({path: './example.txt', contents: 'Hello, world!'});
console.log(file.path); // Outputs: './example.txt'
console.log(file.basename); // Outputs: 'example.txt'

Handling errors and messages

This feature is useful for adding error or warning messages to a file, which can be particularly helpful in linting tools or compilers. The example demonstrates adding an error message to a vfile and logging all associated messages.

const vfile = require('vfile');

const file = vfile();
file.message('Unknown error', {line: 1, column: 1});
console.log(file.messages);

Other packages similar to vfile

vinyl

Vinyl is a virtual file format that is often used in the gulp build system. It is similar to vfile in that it represents file objects in a virtual form, but it is more focused on being used with streams, particularly in the context of gulp's pipelines.

mem-fs

mem-fs provides an in-memory file system which stores file representations similar to vfile. While vfile is designed for text processing with a focus on linting and transformation, mem-fs is geared more towards temporary storage and manipulation of files in memory during tasks like scaffolding or testing.

README

VFile is a virtual file format used by unified, a text processing umbrella (it powers retext for natural language, remark for markdown, and rehype for HTML). Each processors that parse, transform, and compile text, and need a virtual representation of files and a place to store messages about them. Plus, they work in the browser. VFile provides these requirements at a small size, in IE 9 and up.

VFile is different from the excellent vinyl in that it has a smaller API, a smaller size, and focuses on messages.

VFile can be used anywhere where files need a lightweight representation. For example, it’s used in:

• documentation — The documentation system for modern JavaScript
• awoo — Declarative small site generator
• geojsonhint — Complete, fast, standards-based validation for geojson

Installation

npm:

npm install vfile

Table of Contents

• Usage
• Utilities
• Reporters
• API
  • VFile([options])
  • vfile.contents
  • vfile.cwd
  • vfile.path
  • vfile.basename
  • vfile.stem
  • vfile.extname
  • vfile.dirname
  • vfile.history
  • vfile.messages
  • vfile.data
  • VFile#toString([encoding])
  • VFile#message(reason[, position][, origin])
  • VFile#info(reason[, position][, origin])
  • VFile#fail(reason[, position][, origin])
• Contribute
• Acknowledgments
• License

Usage

var vfile = require('vfile')

var file = vfile({path: '~/example.txt', contents: 'Alpha *braavo* charlie.'})

file.path // => '~/example.txt'
file.dirname // => '~'

file.extname = '.md'

file.basename // => 'example.md'

file.basename = 'index.text'

file.history // => ['~/example.txt', '~/example.md', '~/index.text']

file.message('`braavo` is misspelt; did you mean `bravo`?', {
  line: 1,
  column: 8
})

console.log(file.messages)

Yields:

[ { [~/index.text:1:8: `braavo` is misspelt; did you mean `bravo`?]
    message: '`braavo` is misspelt; did you mean `bravo`?',
    name: '~/index.text:1:8',
    file: '~/index.text',
    reason: '`braavo` is misspelt; did you mean `bravo`?',
    line: 1,
    column: 8,
    location: { start: [Object], end: [Object] },
    ruleId: null,
    source: null,
    fatal: false } ]

Utilities

The following list of projects includes tools for working with virtual files. See Unist for projects working with nodes.

• convert-vinyl-to-vfile — Convert from Vinyl
• is-vfile-message — Check if a value is a VMessage object
• to-vfile — Create a virtual file from a file-path (and optionally read it)
• vfile-find-down — Find files by searching the file system downwards
• vfile-find-up — Find files by searching the file system upwards
• vfile-glob — Find files by glob patterns
• vfile-location — Convert between line/column- and range-based locations
• vfile-message — Create a VMessage object (used in vfile itself)
• vfile-statistics — Count messages per category
• vfile-messages-to-vscode-diagnostics — Convert to VS Code diagnostics
• vfile-sort — Sort messages by line/column
• vfile-to-eslint — Convert VFiles to ESLint formatter compatible output

Reporters

The following list of projects show linting results for given virtual files. Reporters must accept Array.<VFile> as their first argument, and return string. Reporters may accept other values too, in which case it’s suggested to stick to vfile-reporters interface.

• vfile-reporter — Stylish reporter
• vfile-reporter-json — JSON reporter
• vfile-reporter-folder-json — JSON reporter with a folder structure
• vfile-reporter-pretty — Pretty reporter

API

VFile([options])

Create a new virtual file. If options is string or Buffer, treats it as {contents: options}. If options is a VFile, returns it. All other options are set on the newly created vfile.

Path related properties are set in the following order (least specific to most specific): history, path, basename, stem, extname, dirname.

It’s not possible to set either dirname or extname without setting either history, path, basename, or stem as well.

Example

vfile()
vfile('console.log("alpha");')
vfile(Buffer.from('exit 1'))
vfile({path: path.join(__dirname, 'readme.md')})
vfile({stem: 'readme', extname: '.md', dirname: __dirname})
vfile({other: 'properties', are: 'copied', ov: {e: 'r'}})

vfile.contents

Buffer, string, null — Raw value.

vfile.cwd

string — Base of path. Defaults to process.cwd().

vfile.path

string? — Path of vfile. Cannot be nullified.

vfile.basename

string? — Current name (including extension) of vfile. Cannot contain path separators. Cannot be nullified either (use file.path = file.dirname instead).

vfile.stem

string? — Name (without extension) of vfile. Cannot be nullified, and cannot contain path separators.

vfile.extname

string? — Extension (with dot) of vfile. Cannot be set if there’s no path yet and cannot contain path separators.

vfile.dirname

string? — Path to parent directory of vfile. Cannot be set if there’s no path yet.

vfile.history

Array.<string> — List of file-paths the file moved between.

vfile.messages

Array.<VMessage> — List of messages associated with the file.

vfile.data

Object — Place to store custom information. It’s OK to store custom data directly on the vfile, moving it to data gives a little more privacy.

VFile#toString([encoding])

Convert contents of vfile to string. If contents is a buffer, encoding is used to stringify buffers (default: 'utf8').

VFile#message(reason[, position][, origin])

Associates a message with the file, where fatal is set to false. Constructs a new VMessage and adds it to vfile.messages.

Returns

VMessage.

VFile#info(reason[, position][, origin])

Associates an informational message with the file, where fatal is set to null. Calls #message() internally.

Returns

VMessage.

VFile#fail(reason[, position][, origin])

Associates a fatal message with the file, then immediately throws it. Note: fatal errors mean a file is no longer processable. Calls #message() internally.

Throws

VMessage.

Contribute

VFile is built by people just like you! Check out contributing.md for ways to get started.

This project has a Code of Conduct. By interacting with this repository, organisation, or community you agree to abide by its terms.

Want to chat with the community and contributors? Join us in Gitter!

Have an idea for a cool new utility or tool? That’s great! If you want feedback, help, or just to share it with the world you can do so by creating an issue in the vfile/ideas repository!

Acknowledgments

The initial release of this project was authored by @wooorm.

Thanks to @contra, @phated, and others for their work on Vinyl, which was a huge inspiration.

Thanks to @brendo, @shinnn, @KyleAMathews, @sindresorhus, and @denysdovhan for contributing commits since!

License

MIT © Titus Wormer